Atom AI Labs - AI-Powered Multi-Tenant Platform

Integration Credentials Guide

This guide explains how to configure credentials for 600+ integrations in ATOM SaaS.

🔑 Credential Architecture

┌─────────────────────────────────────────────────────────────┐
│                     ATOM SaaS Platform                       │
├─────────────────────────────────────────────────────────────┤
│  .env (Platform-Level)          │  Database (Tenant-Level)  │
│  ─────────────────────          │  ──────────────────────── │
│  OAuth App IDs/Secrets          │  User OAuth Tokens        │
│  Platform API Keys              │  BYOK API Keys (OpenAI)   │
│  Stripe/SendGrid Keys           │  Integration Connections  │
└─────────────────────────────────────────────────────────────┘

📥 Push vs Pull Data Sync

Which Apps Require Scheduled Pulling?

**~40% of integrations require scheduled polling** because they don't offer webhooks or have limited real-time capabilities.

Integration	Sync Type	Details
Slack	✅ PUSH	Real-time Events API - instant
Shopify	✅ PUSH	Webhooks for orders, products, customers
HubSpot	✅ PUSH	Webhook subscriptions for all CRM events
Salesforce	✅ PUSH	Streaming API + Outbound Messages
Stripe	✅ PUSH	Webhooks for payments, subscriptions
GitHub	✅ PUSH	Webhooks for commits, PRs, issues
Jira	✅ PUSH	Webhooks for issue changes
Linear	✅ PUSH	Webhooks available
Gmail	⚠️ HYBRID	Push notifications for new mail + pull for history
Outlook	⚠️ HYBRID	Change notifications expire, need re-subscribe
Google Calendar	⚠️ HYBRID	Push notifications + pull for full sync
Airtable	⚠️ HYBRID	Webhooks only on paid plans; free = poll
MS Teams	⚠️ HYBRID	Subscriptions expire after 60 min
QuickBooks	❌ PULL	No webhooks - must poll Change Data Capture API
Xero	❌ PULL	Very limited webhooks - mostly polling
Notion	❌ PULL	No webhooks at all - polling only
Zoho CRM	❌ PULL	Webhooks unreliable - recommend polling
Monday.com	❌ PULL	Webhooks are premium feature
Dropbox	⚠️ HYBRID	Webhooks for file changes, polling for details
Box	✅ PUSH	Webhooks for all events

Real-Time vs Scheduled Sync (Tier-Based)

Your SyncOrchestrator handles polling automatically based on subscription tier:

// From src/lib/sync/orchestrator.ts
SYNC_INTERVALS = {
  FREE:       'WEEKLY',      // Every 7 days (poll-only apps)
  SOLO:       'DAILY',       // Every 24 hours  
  TEAM:       'HOURLY',      // Every hour
  ENTERPRISE: 'REAL_TIME'    // Webhook-first, poll as backup
}

---

🛠️ Platform Credentials (.env)

These are YOUR OAuth app credentials (not customer's).

Required for Core Features

# ═══════════════════════════════════════════════════════════
#                    CORE PLATFORM
# ═══════════════════════════════════════════════════════════

DATABASE_URL="postgresql://user:pass@host:5432/atom_saas?sslmode=require"
REDIS_URL="redis://user:pass@host:6379"

JWT_SECRET="generate-with-openssl-rand-base64-32"
NEXTAUTH_URL="https://app.atom-saas.com"
NEXTAUTH_SECRET="generate-with-openssl-rand-base64-32"

# ═══════════════════════════════════════════════════════════
#                    BILLING & EMAIL
# ═══════════════════════════════════════════════════════════

STRIPE_SECRET_KEY="sk_live_..."
STRIPE_PUBLISHABLE_KEY="pk_live_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
STRIPE_PRICE_ID_SOLO="price_..."
STRIPE_PRICE_ID_TEAM="price_..."
STRIPE_PRICE_ID_ENTERPRISE="price_..."

SMTP_HOST="smtp.sendgrid.net"
SMTP_USER="apikey"
SMTP_PASS="SG...."
FROM_EMAIL="noreply@atom-saas.com"

CRM Integrations

# ═══════════════════════════════════════════════════════════
#                    SALESFORCE
# ═══════════════════════════════════════════════════════════
# Create app: Setup → Apps → App Manager → New Connected App
SALESFORCE_CLIENT_ID="3MVG9..."
SALESFORCE_CLIENT_SECRET="..."
SALESFORCE_CALLBACK_URL="https://app.atom-saas.com/api/integrations/salesforce/callback"

# ═══════════════════════════════════════════════════════════
#                    HUBSPOT
# ═══════════════════════════════════════════════════════════
# Create app: https://developers.hubspot.com/
HUBSPOT_CLIENT_ID="..."
HUBSPOT_CLIENT_SECRET="..."
HUBSPOT_CALLBACK_URL="https://app.atom-saas.com/api/integrations/hubspot/callback"

# ═══════════════════════════════════════════════════════════
#                    ZOHO
# ═══════════════════════════════════════════════════════════
# Create app: https://api-console.zoho.com/
ZOHO_CLIENT_ID="..."
ZOHO_CLIENT_SECRET="..."
ZOHO_CALLBACK_URL="https://app.atom-saas.com/api/integrations/zoho/callback"

Communication Integrations

# ═══════════════════════════════════════════════════════════
#                    SLACK
# ═══════════════════════════════════════════════════════════
# Create app: https://api.slack.com/apps
SLACK_CLIENT_ID="..."
SLACK_CLIENT_SECRET="..."
SLACK_SIGNING_SECRET="..."
SLACK_CALLBACK_URL="https://app.atom-saas.com/api/integrations/slack/callback"

# ═══════════════════════════════════════════════════════════
#                    GOOGLE (Gmail, Calendar, Drive)
# ═══════════════════════════════════════════════════════════
# Create app: https://console.cloud.google.com/
GOOGLE_CLIENT_ID="...apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="..."
GOOGLE_CALLBACK_URL="https://app.atom-saas.com/api/integrations/callback"

# ═══════════════════════════════════════════════════════════
#                    MICROSOFT (Outlook, Teams, OneDrive)
# ═══════════════════════════════════════════════════════════
# Create app: https://portal.azure.com/ → App registrations
MICROSOFT_CLIENT_ID="..."
MICROSOFT_CLIENT_SECRET="..."
MICROSOFT_TENANT_ID="common"
MICROSOFT_CALLBACK_URL="https://app.atom-saas.com/api/integrations/callback"

E-commerce & Finance

# ═══════════════════════════════════════════════════════════
#                    SHOPIFY
# ═══════════════════════════════════════════════════════════
# Create app: https://partners.shopify.com/
SHOPIFY_API_KEY="..."
SHOPIFY_API_SECRET="..."
SHOPIFY_SCOPES="read_products,write_orders,read_customers"

# ═══════════════════════════════════════════════════════════
#                    QUICKBOOKS
# ═══════════════════════════════════════════════════════════
# Create app: https://developer.intuit.com/
QUICKBOOKS_CLIENT_ID="..."
QUICKBOOKS_CLIENT_SECRET="..."
QUICKBOOKS_CALLBACK_URL="https://app.atom-saas.com/api/integrations/callback"

# ═══════════════════════════════════════════════════════════
#                    XERO
# ═══════════════════════════════════════════════════════════
# Create app: https://developer.xero.com/
XERO_CLIENT_ID="..."
XERO_CLIENT_SECRET="..."
XERO_CALLBACK_URL="https://app.atom-saas.com/api/integrations/callback"

---

🗄️ Tenant Credentials (Database)

When a user connects an integration, tokens are stored in tenant_settings:

-- Example: User connects their Salesforce account
INSERT INTO tenant_settings (tenant_id, setting_key, setting_value, encrypted)
VALUES (
  'tenant-uuid',
  'salesforce_tokens',
  '{"access_token": "...", "refresh_token": "...", "instance_url": "..."}',
  true
);

-- BYOK: User provides their own OpenAI key
INSERT INTO tenant_settings (tenant_id, setting_key, setting_value, encrypted)
VALUES (
  'tenant-uuid',
  'OPENAI_API_KEY',
  'sk-proj-...',
  true
);

Token Refresh Flow

// Automatic token refresh (simplified)
async function refreshTokenIfNeeded(tenantId: string, integration: string) {
  const settings = await getTenantSettings(tenantId);
  const tokens = JSON.parse(settings[`${integration}_tokens`]);
  
  if (isExpired(tokens.expires_at)) {
    const newTokens = await oauthClient.refreshToken(tokens.refresh_token);
    await saveTenantSetting(tenantId, `${integration}_tokens`, newTokens);
    return newTokens;
  }
  return tokens;
}

---

📋 Quick Setup Checklist

Minimum Viable Production

[ ] DATABASE_URL - PostgreSQL with SSL
[ ] REDIS_URL - For rate limiting & caching
[ ] JWT_SECRET / NEXTAUTH_SECRET - Generate secure secrets
[ ] STRIPE_* - For billing
[ ] SMTP_* - For transactional emails

Top 5 Integrations to Enable First

[ ] **Slack** - Team communication (PUSH)
[ ] **Google** - Gmail, Calendar, Drive (PULL + webhooks)
[ ] **Salesforce** - CRM (PUSH + PULL)
[ ] **Shopify** - E-commerce (PUSH via webhooks)
[ ] **QuickBooks** - Finance (PULL)

---

🔒 Security Best Practices

**Never commit real credentials** - Use .env files (gitignored)
**Encrypt tokens in database** - Use encrypted: true column
**Rotate secrets regularly** - Especially after team changes
**Use least-privilege scopes** - Only request what you need
**Monitor OAuth activity** - Log all token refreshes